// Package c2 提供HTTP请求参数文档相关的功能，用于描述和记录API请求参数信息。
package c2

import (
	"fmt"

	"gitee.com/tuboyou/c2/config"
)

// ParamsDoc 表示一个API请求参数的文档信息
//
// 字段说明：
//
//	Name - 参数名称
//	Description - 参数描述
//	Type - 参数类型，使用config.ParamType枚举
//	Required - 是否必填
//	Default - 默认值
//	Urlencoded - 是否为urlencode编码
type ParamsDoc struct {
	Name        string           `json:"name"`        // 参数名称
	Description string           `json:"description"` // 参数描述
	Type        config.ParamType `json:"type"`        // 参数类型
	Required    bool             `json:"required"`    // 是否必填
	Default     string           `json:"default"`     // 默认值
	Urlencoded  bool             `json:"urlencoded"`  // 是否为urlencode编码
}

// NewParamsDoc 创建一个新的ParamsDoc实例
//
// 参数：
//
//	name - 参数名称
//
// 返回值：
//
//	*ParamsDoc - 新创建的ParamsDoc指针
func NewParamsDoc(name string) *ParamsDoc {
	return &ParamsDoc{Name: name}
}

// SetDescription 设置参数文档的详细信息
//
// 参数：
//
//	description - 参数描述
//	Type - 参数类型，使用config.ParamType枚举
//	Required - 是否必填
//	Default - 默认值
//	Urlencoded - 是否为urlencode编码
//
// 注意：
//
//  1. 该方法会一次性设置除Name之外的所有字段
//  2. 参数类型使用config包中定义的ParamType枚举
func (t *ParamsDoc) SetDescription(description string, Type config.ParamType, Required bool, Default string, Urlencoded bool) {
	t.Description = description
	t.Type = Type
	t.Required = Required
	t.Default = Default
	t.Urlencoded = Urlencoded
}

// String 返回ParamsDoc的字符串表示
//
// 返回值：
//
//	string - 格式化的参数信息字符串
//
// 示例输出：
//
//	"参数名称:username,参数描述:用户登录名,参数类型:string,是否必填:true,默认值:,是否为urlencode编码:false"
func (t *ParamsDoc) String() string {
	return fmt.Sprintf("参数名称:%s,参数描述:%s,参数类型:%s,是否必填:%t,默认值:%s,是否为urlencode编码:%t",
		t.Name, t.Description, config.ParamTypeMap[t.Type], t.Required, t.Default, t.Urlencoded)
}
